Examples and FAQ

This section contains examples that demonstrate the Matrix program, along with a link to frequently asked questions.

Example 1: Generate zonal data

This sample program generates a zonal data file from input files. The resulting zonal file will contain combined data from the input zonal data and a summary of trips to the zones that are in the central business district.

RUN PGM=MATRIX
mati[1]=tripfile.mat
zdati[1]=socoecon.dat,z=#1, pop=#2, area=#3, income=#4, hh1=#5, hh2=#6, hh3=#7
zdati[2]=employ.dat, z=#1, gov=#2, retail=#3, other=#4
ARRAY pop=10, area=10 totemp=10, tothh=10 ; this is a 10 zone problem area[i]=zi.1.area
totemp[i]=zi.2.gov + zi.2.retail + zi.2.other
tothh[i]=zi.1.hh1 + zi.1.hh2 + zi.1.hh3
jloop include=1-5,38,56-100,145-150 ;cbd zones
cbdtrips[j] = cbdtrips[j] + mi.1.tottrips[j]
endjloop
if (i==zones) ; at last zone
jloop ; write a file of zonal records
print file=newzdat.zda form=6 list=j(3) pop[j] area[j] totemp[j] tothh[j]
cbdtrips[j]
endjloop
endif
ENDRUN

Example 2: Obtain I-J values

This example program get I-J values for records with trip tours on them. The MATRIX program processes the tours.dat file. For each leg of the tour, it looks up highway or transit time based on the major mode for that journey. Mode 1 corresponds to highway, transit otherwise.

The program will read each input record from the RECI file and do calculations as specified. The MatVal function is used to randomly access any i-j value from any input matrix.

The format is: MatVal( filenumber, tablenumber, i, j, failvalue)

The failvalue is returned if lookup fails (invalid filenumber, tablenumber, i, or j). This script has been tested for validity, but has not been thoroughly tested for logical content.

RUN PGM=MATRIX

mati=hwytime.mat,trntime.mat
reci=tours.dat, org=23, dst=26

; there are 80 fields on the record, can be referenced by reci.nfield[#].
; Field 23 can also be referenced as ri.org, and field 26 as ri.dst
; setup array to store time values with max of 8 legs on each tour
array hwyt=8 trnt=8
set val=0, vars=hwyt trnt ; initialize output variables
; trips from org to dst
from=ri.org
leg=1
loop stops=32,42,5 ; flds 32,37,42
if (reci.nfield[stops] > 0)
; if main mode org-dst is hwy
if (reci.nfield[76] = 1)
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0)
endif
leg=leg+1
from=reci.nfield[stops]
endif
endloop
; from last stop to dst
if (reci.nfield[76] = 1) ; if main mode org-dst is hwy
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,ri.dst,0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,ri.dst,0)
endif
; trips from dst to org
from=ri.dst
leg=5
loop stops=47,57,5
if (reci.nfield[stops] > 0)
if (reci.nfield[77] = 1) ; if main mode dst-org is hwy
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0)
endif
leg=leg+1
from=reci.nfield[stops]
endif
endloop
; from last stop to org
if (reci.nfield[77] = 1) ; if main mode dst-org is hwy
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,ri.org,0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,ri.org,0)
endif
; write out I/P record(RECI) and append highway and transit time values
print file=tourtime.dat, form=5 list=reci,
hwyt[1],hwyt[2],hwyt[3],hwyt[4],hwyt[5],hwyt[6],hwyt[7],hwyt[8],
trnt[1],trnt[2],trnt[3],trnt[4],trnt[5],trnt[6],trnt[7],trnt[8]
; compute totals of highway and transit time arrays
hwyt_tot=arraysum(hwyt)
trnt_tot=arraysum(trnt)

ENDRUN

Example 3: RECI/RECO processing

This is an example of using RECI/RECO to process DBF data files.

RUN PGM=MATRIX

This is an example of using RECI/RECO to process DBF data files.
FILEI RECI = ZONES_2002.DBF
FILEO RECO[1] = ZONES_2002_NEW.DBF,
FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), EXCLUDERECI=HOUSEHOLDS
FILEO RECO[2] = ZONES_2010.DBF,
FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(4.2), EXCLUDERECI=HOUSEHOLDS
FILEO RECO[3] = ZONES_2020.DBF,
FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(6.2), POP_2020(8.0), HH_2020(8.0), HHsiz_2020(4.2), Pden_2020(6.2), EXCLUDERECI=HOUSEHOLDS

; compute regional base year statistics TotalHH=TotalHH+RECI.NFIELD[5] TotalPop=TotalPop+RECI.NFIELD[6] avgHHsize=TotalPop/TotalHH
; print regional base year statistics
if (I=0)  ; check for end of file
  PRINT LIST='Total Households =       ',TotalHH
  PRINT LIST='Total Population =       ',TotalPop
  PRINT LIST='Average Household size = ',avgHHsize
endif
; rename RECI field
RO.HH_2002=ri.HOUSEHOLDS
; calculate zonal average household size for base year
RO.HHsiz_2002=ri.POP_2002/HH_2002
; calculate zonal population density per/acre for base year
RO.Pden_2002=ri.POP_2002/(ri.AREA/43560)
; factor base year data for 2010
RO.HH_2010=HH_2002*1.2
RO.POP_2010=RECI.NFIELD[6]*1.4
RO.HHsiz_2010=POP_2010/HH_2010
RO.Pden_2010=POP_2010/(ri.AREA/43560)
; factor base year data for 2020
RO.HH_2020=HH_2002*1.5
RO.POP_2020=RECI.NFIELD[6]*1.8
RO.HHsiz_2020=POP_2020/HH_2020
RO.Pden_2020=POP_2020/(ri.AREA/43560)

; write data to defined output files
WRITE  RECO=1,2,3

ENDRUN

Example 4: CHOICE command

This example uses the CHOICE command in MATRIX to estimate a singly-constrained gravity model, constrained on production trip ends.

RUN PGM=MATRIX

FILEO MATO[1] = "C:\CUBETOWN\MODEL\MODELS\SINGLEPRODDIST.MAT" MO=1
NAME=HBW
FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.DBF"
FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS.MAT"

;The general approach for a singly constrained in Voyager is to use the
;MATRIX program and the CHOICE command to implement a destination choice
;model.
;If you require a gamma curve deterrence function rather than the negative exponential,you need to specify the appropriate calculations yourself.
;This example gives a "destination choice" model constrained on production trip ends.
CHOICE ALTERNATIVES=all1, DEMAND=ZI.1.P1, COSTS=mi.1.1,
ODEMAND=1, STARTMW=99,
DESTSPLIT = TOTAL 0.2 all1

;To apply singly constrained on attractions;
;- transpose the cost matrix, saving it to output file
;- run MATRIX, reading the transposed costs, reversing your use of the
; production and attraction data (i.e., TOTAL=ZI.1.A[1] etc)
; to implement a destination choice, with attraction totals as the single constraint.
;- transpose the resulting matrix to correct orientation.

ENDRUN

Example 5: DBI processing using JOINTODBI

This example uses DBI processing to combine two fields from different tables into a new table, using the JOINTTODBI functionality. The inputs and output are stored in an MDB file.

RUN PGM=MATRIX

FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta2",
  FIELDS=ZONE_ ALFA BETA
FILEI DBI[2] = "DBI_Examples.mdb\BETA",
  SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_
FILEI DBI[1] = "DBI_Examples.mdb\ALFA"

ZONES=1

LOOP k=1,DBI.1.NUMRECORDS
x=DBIReadRecord(1,k)
RO.ZONE_=DI.1.ZONE_
RO.ALFA=DI.1.ALFA
RO.BETA=DI.2.BETA

WRITE RECO=1
ENDLOOP

ENDRUN

Example 6: DBI processing using AUTOARRAY

This example performs the same function as Example 5: DBI processing using JOINTODBI. This time, the AUTOARRAY functionality accomplishes the task.

RUN PGM=MATRIX
FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta3",
  FIELDS = ZONE_ ALFA(10.4) BETA(10.4)
FILEI DBI[2] = "DBI_Examples.mdb\BETA",
  AUTOARRAY=BETA
FILEI DBI[1] = "DBI_Examples.mdb\ALFA",
 AUTOARRAY=ALFA

ZONES = 1

LOOP L3=1,DBI.1.NUMRECORDS,1
  RO.ZONE_ = L3
  RO.ALFA = DBA.1.ALFA[L3]
  RO.BETA = DBA.2.BETA[L3]
  WRITE RECO = 1
ENDLOOP

ENDRUN

Example 7: Simple logit model using XCHOICE

This model uses XCHOICE to implement a simple logit model, where demand is allocated between car and bus trips.

RUN PGM=MATRIX MSG='Absolute XChoice'

FILEI MATI[1] = ".\Inputs\COSTCAR.MAT"
FILEI MATI[2] = ".\Inputs\COSTPTBUS.MAT"
FILEI MATI[3] = ".\Inputs\ALLDEMAND.MAT"

FILEO MATO[1] = ".\ABSOLUTE_OD.MAT", MO=15-16

MW[1] = MI.3.1

MW[3] = MI.1.1
MW[4] = MI.2.1

; Absolute logit model
XCHOICE,
;    List choices
  ALTERNATIVES = car, bus,
;    Input total demand
  DEMANDMW = 1,
;    Input costs
  COSTSMW = 3, 4,
;    Forecast demand
  ODEMANDMW = 15,16,
;    Model structure
  SPLIT = TOTAL 0.02 car bus,
;    Forecast composite cost
  SPLITCOMP = 19,
;    Working matrices
  STARTMW = 30

ENDRUN

Example 8: Cost-based nested logit model using XCHOICE

This example employs XCHOICE to implement a hierarchical logit choice model. The top-level options are car and public transportation, with bus and rail as options within public transport.

RUN PGM=MATRIX MSG='Cost Based Nested XChoice'

FILEI MATI[4] = ".\Inputs\AllDemand.mat"
FILEI MATI[3] = ".\Inputs\CostPTrail.mat"
FILEI MATI[1] = ".\Inputs\COSTCAR.MAT"
FILEI MATI[2] = ".\Inputs\COSTPTBUS.MAT"

FILEO MATO[1] = ".\Nested_OD.MAT", MO=14-16

MW[1] = MI.4.1

MW[4] = MI.1.1
MW[5] = MI.2.1
MW[6] = MI.3.1

; Absolute hierarchical logit model
; Specify scale parameters
lambda = 0.02
mu = 0.03

XCHOICE,
;    List choices
  ALTERNATIVES = car bus rail,
;    Input demand
  DEMAND = 1,
;    Input costs
  COSTSMW = 4, 5, 6,
;    Forecast demand
  ODEMANDMW = 14,15,16,
;    Model Structure
;    Top level nest
  SPLIT = TOTAL lambda car pt,
;    Forecast composite cost top level
  SPLITCOMP = 19,
;    PT nest
  SPLIT = PT mu bus rail,
;    Forecast composite cost PT level
  SPLITCOMP = 20,
;   Working matrices
  STARTMW =70

ENDRUN

Frequently asked questions

Please see FAQ - Matrix & Distribution in Frequently Asked Questions.